Aminet 2

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 2 / Aminet AMIGA CDROM (1994)(Walnut Creek)[Feb 1994][W.O. 44790-1].iso / Aminet / mus / play / MP132src.lha / Guido / Guido.doc < prev next >

Wrap

Text File | 1992-05-25 | 19KB | 375 lines

Guido Version 2.1 Copyright (C) 1992 Bryan Ford Distribution ~~~~~~~~~~~~ Unlike MultiPlayer, Guido is NOT distributed under the General Public License. It is distributed under a separate copyright, with different distribution requirements. The distribution requirements are thus: I grant a license to link the library "guido.lib" into my music player program MultiPlayer ONLY. The Guido compiler GComp may be used to generate Guido user interface object files for MultiPlayer ONLY. Guido may be distributed ONLY with MultiPlayer, not by itself or with anything else. Any other use requires written permission directly from me (Bryan Ford). The Guido distribution must include the following files, complete and unchanged: Guido.doc This file GComp User interface specification compiler guido.lib Library to be linked with MultiPlayer guido.h Header file needed by MultiPlayer I know that this is a rather strange distribution requirement, but right now I don't have the time to put together full documentation and everything else needed to release Guido as I did with Bovs and MemMan. I eventually plan to release Guido under a license much like that of Bovs and MemMan (such that you will be allowed to use it freely in freely distributable programs, or for a small license fee in commercial programs). If there's sufficient interest in Guido I'll try and hurry up and release a really presentable version. In the meantime, you can use it to play with MultiPlayer's user interface and see how you like the language-oriented user interface design. What follows is a very brief (and quite outdated) section describing the Guido source code file format. It certainly doesn't say everything about Guido, but it may at least give you enough information to customize MultiPlayer's user interface. I'll work on full documentation some other time. File Format ~~~~~~~~~~~ In this section, I put actual keywords usable in GUI files in all caps for clarity. I have tried not to use all caps for anything but this purpose, so if you see a word in all caps, chances are GComp understands it. GComp, however, doesn't care about case, so you can do whatever you want in the actual GUI file. Type Parameters Description ~~~~ ~~~~~~~~~~ ~~~~~~~~~~~ Byte number 8-bit signed integer. REL adds the specified number to REL number the last value used for this field. STRUCT (char) IMPORT (char) Short number 16-bit signed integer. REL number STRUCT (short) IMPORT (short) Long number 32-bit signed integer. REL number STRUCT (long) IMPORT (long) Pointer label 32-bit pointer. Providing a label without an IMPORT "text" keyword creates a direct reference - the address of that ARRAY (...) label will be used as the pointer. With IMPORT, an NULL indirect reference is created - the label is assumed to STRUCT (ptr) be a pointer variable, which is used as the pointer. IMPORT (ptr) The NULL keyword specifies a null pointer. See below for information about the ARRAY construct. RPointer STRUCT (ptr) Runtime pointer. Same as above, except you MUST use IMPORT (ptr) either STRUCT or IMPORT - no immediate modes are supported. Boolean none 1-bit flag. The presense of such a keyword, unless it STRUCT (long) is followed by a STRUCT or IMPORT keyword, turns the IMPORT (long) flag on. If a STRUCT or IMPORT keyword is used, the variable it refers to must be a 32-bit long int which is interpreted as true if it is nonzero (as in standard C conventions). Bit OR none Presense of one of these keywords causes a particular bit (or a number of bits) to be OR'd into a preceding Byte, Short, or Long value. The Bit OR type is the only type that does not support the STRUCT or IMPORT modifiers. To set these values at runtime, you must directly use the Byte, Short, or Long that these keywords OR their values into. A few notes about Pointers: A text string enclosed in double quotes is treated the same way as in C - a null-terminated string is created elsewhere and the pointer points to the first character of that string. An ARRAY is a special construct mainly for use with CYCLE and MX gadgets. If you enter the keyword ARRAY any place where a Pointer is expected, an array of other Pointers will be created and the "master" pointer will point to the first entry in the array. After the ARRAY keyword you may enter as many other immediate pointers as you want (i.e. labels, "text", NULL, even nested ARRAYs, but not STRUCT or IMPORT). Terminate the list with an END keyword. WINDOW ~~~~~~ Name Type Description ~~~~ ~~~~ ~~~~~~~~~~~ TITLE Pointer String to put in titlebar of window. SCREENTITLE Pointer Same for titlebar of screen while window is active. SCREEN RPointer Screen on which to open this window. LEFT Short Recommended left edge for window. TOP Short Recommended top edge for window. WIDTH Short Width for interior (panel area) of window. HEIGHT Short Height for interior of window. ZLEFT Short These values work the same as the above, but specify ZTOP Short the alternate, "zoomed" state. (This "zoomed" state ZWIDTH Short might actually be an iconified or shrunken state - ZHEIGHT Short it's really just an "alternate" state.) MINWIDTH Short Minimum allowed size for window. Unlike the above MINHEIGHT Short parameters, these DON'T get adjusted for the interior of the window - they specify the minimum width of the entire window, including border. Therefore, make them big enough to prevent funny things happening with unexpectedly large borders. MAXWIDTH Short Maximum allowed size for window. Defaults to basically MAXHEIGHT Short infinite size. Specifies window exterior, like MINWIDTH and MINHEIGHT. FLAGS Long Goes straight into NewWindow.Flags. The following Bit OR keywords apply to this field. SIZEGADGET Bit OR Makes the window sizeable. DRAGBAR Bit OR Makes the window draggable. DEPTHGADGET Bit OR Makes the window depth-arrangeable. CLOSEGADGET Bit OR Provides the window with a close gadget. SIZEBRIGHT Bit OR Puts the size gadget into the right border. SIZEBBOTTOM Bit OR Puts the size gadget into the bottom border. SIMPLEREFRESH Bit OR Application must do all refreshing. (Guido handles all gadget refreshing automatically on simplerefresh Guido panels.) SIMPLE_REFRESH Bit OR Synonym for above. SMARTREFRESH Bit OR Automatic refreshing except when window changes size. SMART_REFRESH Bit OR Synonym for above. SUPERBITMAP Bit OR Virtual bitmap; you must provide BitMap. SUPER_BITMAP Bit OR Synonym for above. BACKDROP Bit OR Puts the window in the background of the screen. REPORTMOUSE Bit OR Floods you with MOUSEMOVE messages. GIMMEZEROZERO Bit OR Creates a double-layered window. BORDERLESS Bit OR Creates a window without a border. ACTIVATE Bit OR Activates the window as soon as it opens. RMBTRAP Bit OR Sends right mouse button messages straight to you. NOCAREREFRESH Bit OR Stifles all refresh messages. IDCMPFLAGS Long Goes straight into NewWindow.IDCMPFlags. The following Bit OR keywords apply to this field. REFRESHWINDOW Bit OR Tells you when the window needs refreshing. (Always include this if you're using Guido Panels on simplerefresh windows.) MOUSEBUTTONS Bit OR Tells you about mouse clicks and unclicks. MOUSEMOVE Bit OR Tells you about every mouse move while your window is active. (Must also use REPORTMOUSE above.) DELTAMOVE Bit OR Use with MOUSEMOVE - gives delta values. GADGETDOWN Bit OR Gadget pressed messages. (MX gadgets use this.) GADGETUP Bit OR Gadget released messages. (Most gadgets use this.) MENUVERIFY Bit OR Tells you when the user wants to use the menus. MENUPICK BIT OR Gives information about menu selections. MENUHELP Bit OR Tells you when the HELP key is pressed in the menus. SIZEVERIFY Bit OR Tells you when the user wants to size the window. NEWSIZE Bit OR Tells you when the user has sized the window. CLOSEWINDOW Bit OR Tells you when the close gadget was pressed. RAWKEY Bit OR Gives you raw, unadulterated keycodes. VANILLAKEY Bit OR Gives you preprocessed ASCII keystrokes. NEWPREFS Bit OR Tells you when system preferences have changed. DISKINSERTED Bit OR Duhh, tells you when George Bush sneezes. DISKREMOVED Bit OR Tells you when somebody sights Martians. ACTIVEWINDOW Bit OR Tells you when your window becomes active. INACTIVEWINDOW Bit OR Tells you when somebody else steals the show. INTUITICKS Bit OR One of these every tenth of a second. IDCMPUPDATE Bit OR Duhh, who knows? I don't have the 2.0 manuals... CHANGEWINDOW Bit OR Haven't the slightest... BUTTONIDCMP Bit OR Include this if you use buttons. CHECKBOXIDCMP Bit OR Include this if you use checkboxes. MXIDCMP Bit OR Include this if you use MX gadgets. RADIOIDCMP Bit OR Synonym for above. CYCLEIDCMP Bit OR Include this if you use cycle gadgets. NUMBERIDCMP Bit OR Include this if you use number (read-only) gadgets. INTEGERIDCMP Bit OR Include this if you use integer (editable) gadgets. TEXTIDCMP Bit OR Include this if you use text (read-only) gadgets. STRINGIDCMP Bit OR Include this if you use string (editable) gadgets. LISTVIEWIDCMP Bit OR Include this if you use listviews. Gadgets ~~~~~~~ This section lists the keywords common to all (or at least most) gadget types. Name Type Description ~~~~ ~~~~ ~~~~~~~~~~~ EXPORT Pointer When this gadget is created, fills in the pointer pointed to by this pointer with a pointer to the newly created Gadget, which can be used in Guido library function calls. WIDTH Short Size of gadget (optional). HEIGHT Short LABEL Pointer Label text for this gadget. LABELFLAGS Long Corresponds to GadTools' NewGadget.Flags field. The following Bit OR keywords go into this field. LABELLEFT Bit OR Right-aligns the label to the left of the gadget. LABELRIGHT Bit OR Left-aligns the label to the right of the gadget. LABELABOVE Bit OR Centers the label above the gadget. LABELBELOW Bit OR Centers the label below the gadget. LABELIN Bit OR Chucks the label smack dab in the middle of the gadget. HIGHLABEL Bit OR Draws the label in a more shocking color. BUTTON ~~~~~~ This gadget type has no extra keywords. CHECKBOX ~~~~~~~~ Name Type Description ~~~~ ~~~~ ~~~~~~~~~~~ CHECKED Boolean Pre-select the checkbox. CYCLE and MX (synonym RADIO) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Name Type Description ~~~~ ~~~~ ~~~~~~~~~~~ OPTIONS Pointer Points to a null-terminated array of string pointers defining the selection options. You can use the ARRAY keyword to conveniently build these arrays within the GUI file, or use IMPORT or STRUCT to reference your own arrays. ACTIVE Long Number of the initially active option, counting from zero. TEXT ~~~~ Name Type Description ~~~~ ~~~~ ~~~~~~~~~~~ TEXT Pointer Defines the text to display initially in the text box. COPYTEXT Boolean If set, an internal copy of the text string is kept so you can free your own string after you set the text. BORDER Boolean If set, a beautiful sunken border appears around the text. STRING ~~~~~~ Name Type Description ~~~~ ~~~~ ~~~~~~~~~~~ STRING Pointer Defines the initial string for the string gadget. This string is immediately copied to an internal buffer. MAXSIZE Long Defines the length of the string buffer allocated. NUMBER ~~~~~~ Name Type Description ~~~~ ~~~~ ~~~~~~~~~~~ NUMBER Long Number to display initially. BORDER Boolean Draws a sunken border around the number. INTEGER ~~~~~~~ Name Type Description ~~~~ ~~~~ ~~~~~~~~~~~ NUMBER Long Number to use initially as the default in the gadget. MAXSIZE Long Maximum number of digits the user may enter. LISTVIEW ~~~~~~~~ Name Type Description ~~~~ ~~~~ ~~~~~~~~~~~ LIST Pointer Pointer to an Exec-style list to display initially. The strings displayed are in the ln_Name fields. READONLY Boolean If you set this, the listview will appear sunken and the user won't be able to select items. SHOWSELECTED Special If you use this keyword, the currently selected entry will automatically be shown below the listview. To simply display the currently selected entry, enter SHOWSELECTED NULL. To allow the currently selected entry to be edited, put a STRING gadget definition immediately before this one and use SHOWSELECTED PREV. TOPITEM Long Specifies the item number to be displayed at the top of the ListView list, counting from zero. ACTIVE Long Specifies the item number to be initially selected, counting from zero. Use -1 for no initial selection. FILEREQ ~~~~~~~ Name Type Description ~~~~ ~~~~ ~~~~~~~~~~~ MULTISELECT Boolean Allows the user to select several files at once. SAVE Boolean Inverts the imagery and disables double-clicking. HAIL Pointer Text to display in the filerequester titlebar. OK Pointer Text to display in the OK gadget. CANCEL Pointer Text to display in the Cancel gadget. PATTERN Pointer AmigaDOS wildcard pattern - only filenames that get past this will get displayed. WINDOW RPointer Pointer to the window over which to show the file requester (mainly used for finding the screen to put it in). DONEMASK Long Specifies a signal mask which the filerequester will send you when the user has closed it (i.e. pressed OK or Cancel). You can use IMPORT or STRUCT and AllocSignal() to get a signal at runtime, or you can be lazy and use one of the Bit OR keywords below to use standard AmigaDOS signal bits. DONECTRLC Bit OR Sends you SIGBREAKF_CTRL_C when done. DONECTRLD Bit OR Sends you SIGBREAKF_CTRL_D when done. DONECTRLE Bit OR Sends you SIGBREAKF_CTRL_E when done. DONECTRLF Bit OR Sends you SIGBREAKF_CTRL_F when done. Version History ~~~~~~~~~~~~~~~ 2.1 (R3, May 25, 1992) Released in GNU-ized MultiPlayer 1.30. Added separate copyright messages, made it at least somewhat releasable. 2.0 (R2, May 5, 1992) Released in MultiPlayer 1.20. Variable fonts. 1.0 (R1) Guido before the dawn of history.